<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: Startup CAT1B</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__group__system__config__cm33.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">API Reference</a>  </div>
  <div class="headertitle">
<div class="title">Startup CAT1B<div class="ingroups"><a class="el" href="group__group__startup__config.html">Startup</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">General Description</h2>
<p>Provides device startup, system configuration, and linker script files. </p>
<p>The system startup provides the followings features:</p><ul>
<li><a class="el" href="group__group__system__config__cm33.html#group_system_config_device_memory_definition_cm33">Device Memory Definition</a></li>
<li><a class="el" href="group__group__system__config__cm33.html#group_system_config_device_initialization_cm33">Device Initialization</a></li>
<li><a class="el" href="group__group__system__config__cm33.html#group_system_config_heap_stack_config_cm33">Heap and Stack Configuration</a></li>
<li><a class="el" href="group__group__system__config__cm33.html#group_system_config_default_handlers_cm33">Default Interrupt Handlers Definition</a></li>
<li><a class="el" href="group__group__system__config__cm33.html#group_system_config_device_vector_table_cm33">Vectors Table Copy from ROM/Flash to RAM</a></li>
</ul>
<h1><a class="anchor" id="group_system_config_configuration_cm33"></a>
Configuration Considerations</h1>
<h2><a class="anchor" id="group_system_config_device_memory_definition_cm33"></a>
Device Memory Definition</h2>
<p>Allocation of different types of memory such as the ROM, flash and RAM etc. for the CPU is defined by the linker scripts.</p>
<dl class="section note"><dt>Note</dt><dd>The linker files provided with the PDL are generic and handle all common use cases. Your project may not use every section defined in the linker files. In that case you may see warnings during the build process. To eliminate build warnings in your project, you can simply comment out or remove the relevant code in the linker file.</dd></dl>
<p><b>For CYW20829</b></p>
<p><b>ARM GCC</b><br />
The ROM, flash and RAM sections for the CPU are defined in the linker file: 'cyw20829_ns_flash_cbus.ld', where 'ns' indicates that the linker script file is for non-secure image. For devices without security extension, there will be only one linker file and it is always non-secure.</p>
<p>Memory sections are for the GNU GCC ARM tool set is defined in the linker file cyw20829_ns_flash_cbus.ld. Following are the important memory sections for the User/Application image.</p>
<p>Memory sections are for the GNU GCC ARM tool set is defined in the linker file &lt;device&gt;_ns.sct. Following are the important memory sections for the User/Application image. </p><div class="fragment"><div class="line">code        (rx)  : ORIGIN = CODE_VMA,      LENGTH = CODE_BS_SIZE  Starting address and the size of Non-secure bootstrap code</div><div class="line">bsData      (rwx) : ORIGIN = DATA_BS_VMA,   LENGTH = DATA_BS_SIZE  Starting address and the size of Non-secure bootstrap data</div><div class="line">appCodeRam  (rx)  : ORIGIN = DATA_CBUS_VMA, LENGTH = DATA_SIZE     Starting address and the size of Non-secure application ram functions</div><div class="line">data        (rwx) : ORIGIN = DATA_VMA,      LENGTH = DATA_SIZE     Starting address and the size of Non-secure application data</div><div class="line">xip         (rx)  : ORIGIN = XIP_VMA,       LENGTH = XIP_SIZE      Starting address and the size of Non-secure application code</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>In CYW20829, the Bootstrap memory is used to place the startup code along with SMIF driver in the ram area. The size requirement for Bootstrap may vary depending on the number of functions that are linked from SMIF driver. When more functions are linked, you may see linker error. In order to fix this you need to increase Bootstarp memory size in the ram by modifying the value of BOOTSTRAP_OFFSET_RAM.<br />
E.g. if linker error suggests to increase by 8192 bytes, then you need to move the starting address of the bootstrap memory up by 8192 bytes as shown below <br />
BOOTSTRAP_OFFSET_RAM = 0x0001E000; Old value<br />
BOOTSTRAP_OFFSET_RAM = 0x0001C000; New value<br />
Because of the change in the bootstrap size, you may also need to move the application start address in the flash. If you see a linker error after above change, then you need to modify the application code offset APPCODE_OFFSET_FLASH in the flash.<br />
E.g. if linker error suggests 256 bytes overlap of .appText LMA with .bootstrapText LMA, you need to move the application start offset in the flash down by 256 bytes as shown below<br />
APPCODE_OFFSET_FLASH = 0x00002200; Old value<br />
APPCODE_OFFSET_FLASH = 0x00002300; New value</dd></dl>
<p><b>ARM Compiler</b><br />
The ROM, flash and RAM sections for the CPU are defined in the linker file: 'cyw20829_ns_flash_cbus.sct', where 'ns' indicates that the linker script file is for non-secure image. For devices without security extension, there will be only one linker file and it is always non-secure.</p>
<p>Memory sections are for the GNU GCC ARM tool set is defined in the linker file cyw20829_ns_flash_cbus.sct. Following are the important memory sections for the User/Application image. </p><div class="fragment"><div class="line">bootstrapText_vma   Starting address of bootstrap code</div><div class="line">bootstrapText_size  Size of memory reserved <span class="keywordflow">for</span> Bootstrap code</div><div class="line">bootstrapData_vma   Starting address of Bootstrap data</div><div class="line">appText_vma         Stating address of application code</div><div class="line">appData_vma         Stating address of application data</div></div><!-- fragment --><p><b>IAR</b><br />
The ROM, flash and RAM sections for the CPU are defined in the linker file: 'cyw20829_ns_flash_cbus.icf', where 'ns' indicates that the linker script file is for non-secure image. For devices without security extension, there will be only one linker file and it is always non-secure.</p>
<p>Memory sections are for the GNU GCC ARM tool set is defined in the linker file cyw20829_ns_flash_cbus.icf. Following are the important memory sections for the User/Application image. </p><div class="fragment"><div class="line">define region CODE_region     = mem:[from CODE_VMA size CODE_BS_SIZE];      Bootstrap code region and size</div><div class="line">define region DATA_BS_region  = mem:[from DATA_BS_VMA size DATA_BS_SIZE];   Bootstrap data region and size</div><div class="line">define region DATA_region     = mem:[from DATA_VMA size DATA_SIZE];         Application data region and size</div><div class="line">define region XIP_region      = mem:[from XIP_VMA size XIP_SIZE];           Application code (xip) region and size</div></div><!-- fragment --><h2><a class="anchor" id="group_system_config_device_initialization_cm33"></a>
Device Initialization</h2>
<p><b>CM33 Without ARM TrustZone Support:</b><br />
 Below MSC describes the simplified startup sequence starting from reset release of the core. As soon as the reset is released, the execution starts form the ROM interrupt vector table reset vector. The ROM code initializes the basic clock needed to access and configure MMIO registers and then sets up debug port so that the debugger can be attached. After it finishes all the necessary initialization, it reads the bootstrap (part of non secure application image) location, size from TOC2 header and loads the bootstrap code into SRAM.</p>
<p>Before switching execution to the non-secure application code, the ROM code needs to initialize the stack pointer MSP_NS for the non-secure code. This value is picked form the first entry in the non-secure bootstrap's vector table __ns_vector_table. Once the non-secure stack is initialized, the ROM code will call the non-secure code entry point which is nothing but the Reset_Handler. Address of this function is picked form the second entry in the non-secure vector table __ns_vector_table and type casting it to function pointer.</p>
<p>In the non-secure Reset_Handler, the vector table is copied to RAM area and then the address of the vector table is set to VTOR register. This calls SystemInit function which internally calls Cy_PDL_Init, Cy_SystemInit and SystemCoreClockUpdate functions. Then it calls C runtime initialization function which calls main function of the application code.</p>
<p>Below sequence diagram captures the initialization process in the startup code. </p><div class="image">
<img src="cm33_ns_startup.png" alt="cm33_ns_startup.png"/>
</div>
<h2><a class="anchor" id="group_system_config_heap_stack_config_cm33"></a>
Heap and Stack Configuration</h2>
<p>By default, the stack size is set to 0x00001000 and the entire remaining ram is used for the heap</p>
<h3><a class="anchor" id="group_system_config_heap_stack_config_gcc_cm33"></a>
ARM GCC</h3>
<ul>
<li><b>Editing source code files for non-secure image</b><br />
The stack and heap sizes are defined in the linker script file: 'cyw20829_ns_flash_cbus.ld'. Change the stack size by modifying the following line:<br />
<div class="fragment"><div class="line">STACK_SIZE = 0x00001000; </div></div><!-- fragment --> Remaining free RAM is used as heap.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>Correct operation of malloc and related functions depends on the working implementation of the 'sbrk' function. Newlib-nano (default C runtime library used by the GNU Arm Embedded toolchain) provides weak 'sbrk' implementation that doesn't check for heap and stack collisions during excessive memory allocations. To ensure the heap always remains within the range defined by __HeapBase and __HeapLimit linker symbols, provide a strong override for the 'sbrk' function: <div class="fragment"><div class="line"><span class="keywordtype">void</span> * _sbrk(uint32_t incr)</div><div class="line">{</div><div class="line">    <span class="keyword">extern</span> uint8_t __HeapBase, __HeapLimit;</div><div class="line">    <span class="keyword">static</span> uint8_t *heapBrk = &amp;__HeapBase;</div><div class="line">    uint8_t *prevBrk = heapBrk;</div><div class="line">    <span class="keywordflow">if</span> (incr &gt; (uint32_t)(&amp;__HeapLimit - heapBrk))</div><div class="line">    {</div><div class="line">        errno = ENOMEM;</div><div class="line">        CY_HALT();</div><div class="line">    }</div><div class="line">    heapBrk += incr;</div><div class="line">    <span class="keywordflow">return</span> prevBrk;</div><div class="line">}</div></div><!-- fragment -->For FreeRTOS-enabled multi-threaded applications, it is sufficient to include clib-support library that provides newlib-compatible implementations of 'sbrk', '__malloc_lock' and '__malloc_unlock': <br />
 <a href="https://github.com/Infineon/clib-support">https://github.com/Infineon/clib-support</a>.</dd></dl>
<h3><a class="anchor" id="group_system_config_heap_stack_config_arm_cm33"></a>
ARM Compiler</h3>
<ul>
<li><b>Editing source code files for non-secure image</b><br />
The stack sizes are defined in the linker script file: 'cyw20829_ns_flash_cbus.sct'. Change the stack by modifying the following lines:<br />
<div class="fragment"><div class="line"><span class="preprocessor">#define STACK_SIZE  0x00001000 </span></div></div><!-- fragment --> Remaining free RAM is used as heap.</li>
</ul>
<h3><a class="anchor" id="group_system_config_heap_stack_config_iar_cm33"></a>
IAR</h3>
<ul>
<li><b>Editing source code files for non-secure image</b><br />
The stack and heap sizes are defined in the linker script file: 'cyw20829_ns_flash_cbus.icf'. Change the stack size by modifying the following line:<br />
<div class="fragment"><div class="line">define symbol STACK_SIZE = 0x00001000; </div></div><!-- fragment --> Remaining free RAM is used as heap.</li>
</ul>
<h2><a class="anchor" id="group_system_config_default_handlers_cm33"></a>
Default Interrupt Handlers Definition</h2>
<p>The default interrupt handler functions are dummy handler in the startup file.<br />
Below is the default handler for the non-secure interrupts:<br />
</p><div class="fragment"><div class="line"> interrupt_type <span class="keywordtype">void</span> InterruptHandler(<span class="keywordtype">void</span>) {</div><div class="line">   <span class="keywordflow">while</span>(1);</div><div class="line">} </div></div><!-- fragment --><h2><a class="anchor" id="group_system_config_device_vector_table_cm33"></a>
Vectors Table Copy from ROM/Flash to RAM</h2>
<p>This process uses memory sections defined in the linker script. The startup code copies the default vector table contents to the non-secure SRAM region specified by the linker script. APIs are provided in the sysint driver to hook user implemented handler replacing the default handler for the corresponding interrupt.</p>
<p>Following tables provide the address of the default and non-secure SRAM interrupt vector table for different supported compilers. </p>
<h3><a class="anchor" id="group_system_config_device_vector_table_gcc_cm33"></a>
ARM GCC</h3>
<p>The linker script file is 'cyw20829_ns_flash_cbus.ld'. For non-secure world, it uses the following variable.<br />
 Copy interrupt vectors from ROM/flash to RAM: <br />
 From:</p><div class="fragment"><div class="line">__ns_vector_table </div></div><!-- fragment --><p> To:</p><div class="fragment"><div class="line">__ns_vector_table_rw </div></div><!-- fragment --><p> The vector table address (and the vector table itself) are defined in the ns_start_&lt;device&gt;.c startup file corresponding to non-secure world. The code in these files copies the vector table from ROM/Flash to RAM.</p>
<h3><a class="anchor" id="group_system_config_device_vector_table_mdk_cm33"></a>
ARM Compiler</h3>
<p>The linker script file is 'cyw20829_ns_flash_cbus.sct'. For non-secure world, it uses the following variable.<br />
 Copy interrupt vectors from ROM/flash to RAM: <br />
 From:</p><div class="fragment"><div class="line">__ns_vector_table </div></div><!-- fragment --><p> To:</p><div class="fragment"><div class="line">__ns_vector_table_rw </div></div><!-- fragment --><p> The vector table address (and the vector table itself) are defined in the ns_start_&lt;device&gt;.c startup file corresponding to non-secure world. The code in these files copies the vector table from ROM/Flash to RAM.</p>
<h3><a class="anchor" id="group_system_config_device_vector_table_iar_cm33"></a>
IAR</h3>
<p>The linker script file is 'cyw20829_ns_flash_cbus.icf'. For non-secure world, it uses the following variable.<br />
 Copy interrupt vectors from ROM/flash to RAM: <br />
 From:</p><div class="fragment"><div class="line">__ns_vector_table </div></div><!-- fragment --><p> To:</p><div class="fragment"><div class="line">__ns_vector_table_rw </div></div><!-- fragment --><p> The vector table address (and the vector table itself) are defined in the ns_start_&lt;device&gt;.c startup file corresponding to non-secure worlds. The code in these files copies the vector table from ROM/Flash to RAM.</p>
<h1><a class="anchor" id="group_system_config_changelog_cm33"></a>
Changelog</h1>
<table class="doxtable">
<tr>
<th>Version </th><th>Changes </th><th>Reason for Change  </th></tr>
<tr>
<td>1.2 </td><td>Added new internal functions. </td><td>Added support for DSRAM Setup for CAT1B devices.  </td></tr>
<tr>
<td>1.1 </td><td>Restructured documentation and internal function behaviour. </td><td>User experience enhancement.  </td></tr>
<tr>
<td>1.0 </td><td>Initial version </td><td></td></tr>
</table>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
API Reference</h2></td></tr>
<tr class="memitem:group__group__system__config__macro__cm33"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__system__config__macro__cm33.html">Macros</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
